# 入门教程

```{admonition} 本文引用的文件
:class: note

- [docs/docs/zh_CN/tutorials/basics/index.rst](../../../../products/mpython/tutorials/basics/index.rst)
- [docs/docs/zh_CN/tutorials/basics/repl.rst](../../../../products/mpython/tutorials/basics/repl.rst)
- [docs/docs/zh_CN/tutorials/basics/oled.rst](../../../../products/mpython/tutorials/basics/oled.rst)
- [docs/docs/zh_CN/tutorials/basics/neopixel.rst](../../../../products/mpython/tutorials/basics/neopixel.rst)
- [docs/docs/zh_CN/tutorials/basics/buzz.rst](../../../../products/mpython/tutorials/basics/buzz.rst)
- [docs/docs/zh_CN/tutorials/basics/buttons.rst](../../../../products/mpython/tutorials/basics/buttons.rst)
- [docs/docs/zh_CN/tutorials/basics/touchpad.rst](../../../../products/mpython/tutorials/basics/touchpad.rst)
- [docs/docs/zh_CN/tutorials/basics/sound.rst](../../../../products/mpython/tutorials/basics/sound.rst)
- [docs/docs/zh_CN/tutorials/basics/light.rst](../../../../products/mpython/tutorials/basics/light.rst)
- [docs/docs/zh_CN/tutorials/basics/accelerometer.rst](../../../../products/mpython/tutorials/basics/accelerometer.rst)
- [docs/docs/zh_CN/tutorials/basics/network/index.rst](../../../../products/mpython/tutorials/basics/network/index.rst)
- [docs/docs/zh_CN/tutorials/basics/uart.rst](../../../../products/mpython/tutorials/basics/uart.rst)
- [docs/docs/zh_CN/tutorials/basics/io/index.rst](../../../../products/mpython/tutorials/basics/io/index.rst)
- [esp32s3/docs/3_examples/basics/index.rst](../../../../products/mpython-s3/3_examples/basics/index.rst)
```

## 产品概述
本入门教程面向掌控板初学者，围绕REPL交互、OLED显示、RGB LED、音乐、按键、触摸、麦克风、光线、加速度、网络、串口与引脚等基础功能，提供循序渐进的学习路径。通过“原理说明 + 示例代码 + 动手实践”的方式，帮助读者快速上手MicroPython开发，完成从点亮LED到联网通信的完整学习闭环。

## 核心业务流程
- 连接与交互：通过USB串口建立REPL会话，进行交互式编程与调试。
- 输入感知：读取按键、触摸、声音、光线、加速度等传感器数据。
- 输出控制：在OLED上显示文本/图形，驱动RGB LED，播放音乐或蜂鸣器提示。
- 通信扩展：使用UART与其他设备通信，或通过WiFi进行网络访问（进阶）。
- 综合应用：将多模块组合，实现如“光控灯”“水平仪”“串口收发”等小项目。

```text
flowchart TD
A["启动与连接"] --> B["REPL交互"]
B --> C{"选择功能"}
C --> |显示| D["OLED显示"]
C --> |灯光| E["RGB LED"]
C --> |声音| F["音乐/蜂鸣器"]
C --> |输入| G["按键/触摸/声音/光线/加速度"]
C --> |通信| H["串口UART"]
C --> |网络| I["WiFi/HTTP(进阶)"]
D --> J["综合项目"]
E --> J
F --> J
G --> J
H --> J
I --> J
```

## 功能模块清单
- REPL：交互式命令行环境，便于快速验证代码与调试。
- OLED显示：文本、图形、图片与动画显示。
- RGB LED：板载WS2812灯珠与外部彩带控制。
- 音乐：内置旋律、自定义音符与频率控制。
- 按键：A/B按键状态读取与中断处理。
- 触摸：6个触摸焊盘读取与阈值配置。
- 麦克风：ADC采集环境声音强度。
- 光线：ADC采集环境光照强度。
- 加速度：三轴加速度与角度计算。
- 网络：WiFi连接与HTTP请求（进阶）。
- 串口：UART收发数据，对接蓝牙/外设。
- 引脚：数字/模拟I/O与PWM输出。

## 数据与状态
- 传感器数据流：传感器→ADC/总线→mpython对象→应用逻辑→输出（显示/灯光/声音/通信）。
- 关键状态：
  - 按键/触摸：按下/释放、计数、事件回调。
  - 显示：帧缓冲内容、刷新时机。
  - 音频：播放/暂停/停止、音量、录音状态。
  - 网络：连接状态、请求响应。
  - 串口：发送/接收缓冲区、超时与解析。
- 数据所有权边界：
  - 传感器与IO由底层驱动管理，用户通过mpython封装接口访问。
  - 显示与音频需显式刷新或释放资源。
  - 网络与串口需关注超时与异常处理。

## 关键约束与边界
- 硬件限制：
  - ADC分辨率与量程：声音/光线为12位ADC，最大值约4095。
  - 加速度计量程默认±2g，可配置范围与分辨率。
  - 部分引脚复用：P4用于光线传感器、P10用于声音传感器，不可作为通用引脚。
- 软件依赖：
  - 显示基于framebuf与SSD1106（ESP32）或st7789（ESP32-S3 TFT）。
  - 音乐模块兼容micro:bit；ESP32支持audio编解码与TTS。
  - 网络与串口依赖machine与系统驱动。
- 性能与功耗：
  - 频繁刷新显示与高频采样会增加功耗与CPU占用。
  - 建议按需刷新、合理延时与批量写入。
- 安全与稳定性：
  - 网络请求需处理超时与异常。
  - 串口通信需校验数据格式与长度。
  - 中断回调函数需简洁高效，避免阻塞。

## 各主题要点与参考路径
- REPL：串口连接、行编辑、Tab补全、粘贴模式与控制命令。
  - 参考：[docs/docs/zh_CN/tutorials/basics/repl.rst:1-147]
- OLED显示：文本、形状、图片与动态显示。
  - 参考：[docs/docs/zh_CN/tutorials/basics/oled.rst:1-260]
- RGB LED：板载与外部彩带控制、效果演示。
  - 参考：[docs/docs/zh_CN/tutorials/basics/neopixel.rst:1-144]
- 音乐：内置旋律、自编乐谱、频率控制。
  - 参考：[docs/docs/zh_CN/tutorials/basics/buzz.rst:1-90]
- 按键：状态读取与中断处理。
  - 参考：[docs/docs/zh_CN/tutorials/basics/buttons.rst:1-58]
- 触摸：触摸焊盘读取与阈值配置。
  - 参考：[docs/docs/zh_CN/tutorials/basics/touchpad.rst:1-26]
- 麦克风：声音强度读取与显示。
  - 参考：[docs/docs/zh_CN/tutorials/basics/sound.rst:1-36]
- 光线：光照强度读取与光控灯示例。
  - 参考：[docs/docs/zh_CN/tutorials/basics/light.rst:1-37]
- 加速度：三轴读数、倾斜角度与水平球示例。
  - 参考：[docs/docs/zh_CN/tutorials/basics/accelerometer.rst:1-145]
- 网络：基础概念与协议（TCP/UDP/HTTP/JSON）。
  - 参考：[docs/docs/zh_CN/tutorials/basics/network/index.rst:1-14]
- 串口：UART构建、发送与接收。
  - 参考：[docs/docs/zh_CN/tutorials/basics/uart.rst:1-111]
- 引脚：数字/模拟I/O与PWM。
  - 参考：[docs/docs/zh_CN/tutorials/basics/io/index.rst:1-9]
- ESP32-S3基础示例索引（含LCD、WiFi、音频等）：
  - 参考：[esp32s3/docs/3_examples/basics/index.rst:1-25]

## 架构总览
```text
graph TB
subgraph "用户程序"
APP["应用逻辑<br/>MPython脚本"]
end
subgraph "库层"
M["mpython模块<br/>OLED/RGB/音乐/传感器/WiFi/串口"]
MB["machine/framebuf/SSD1106/NeoPixel"]
end
subgraph "驱动层"
DRV["C级驱动<br/>modmusic/modmotion/modnetwork等"]
HW["硬件外设<br/>OLED/RGB/传感器/音频/网络"]
end
APP --> M
M --> MB
MB --> DRV
DRV --> HW
```

## 详细组件分析

### REPL交互
- 目标：通过串口终端进入MicroPython REPL，进行即时编程与调试。
- 关键点：波特率115200、行编辑、历史记录、Tab补全、粘贴模式、Ctrl-C中断、软重启。
- 实践：打印文本、调用mpython对象显示字符、循环控制LED。
- 参考路径：
  - [docs/docs/zh_CN/tutorials/basics/repl.rst:1-147]

```text
sequenceDiagram
participant 用户 as "用户"
participant 终端 as "串口终端"
participant REPL as "MicroPython REPL"
用户->>终端 : 打开串口(115200)
终端->>REPL : 发送回车/命令
REPL-->>终端 : 执行并返回结果/错误
用户->>终端 : Ctrl-C中断/粘贴模式
终端-->>REPL : 取消/执行多行代码
```

**章节来源**
- [docs/docs/zh_CN/tutorials/basics/repl.rst:1-147]

### OLED显示
- 目标：在128x64 OLED上显示文本、图形、图片与动画。
- 关键点：DispChar/DispChar_font、fill/show、像素/线条/矩形绘制、bitmap与blit。
- 实践：Hello World、绘制图形、加载BMP/PBM逐帧动画。
- 参考路径：
  - [docs/docs/zh_CN/tutorials/basics/oled.rst:1-260]

```text
flowchart TD
S["开始"] --> T["准备帧缓冲"]
T --> D["绘制文本/图形/图片"]
D --> R["刷新显示 show()"]
R --> L["循环更新/动画"]
L --> E["结束"]
```

**章节来源**
- [docs/docs/zh_CN/tutorials/basics/oled.rst:1-260]

### RGB LED
- 目标：控制板载WS2812灯珠与外部彩带，实现颜色与动态效果。
- 关键点：rgb对象赋值、write()刷新、neopixel.NeoPixel初始化与效果函数。
- 实践：单灯变色、全灯填充、彩虹/弹跳/循环效果。
- 参考路径：
  - [docs/docs/zh_CN/tutorials/basics/neopixel.rst:1-144]

```text
classDiagram
class NeoPixel {
+__setitem__(index, color)
+write()
+fill(color)
}
class 应用 {
+设置颜色
+刷新显示
+循环效果
}
应用 --> NeoPixel : "控制"
```

**章节来源**
- [docs/docs/zh_CN/tutorials/basics/neopixel.rst:1-144]

### 音乐
- 目标：播放内置旋律、自定义音符与频率变化。
- 关键点：music.play、music.pitch、music.set_tempo、内置曲目常量。
- 实践：生日歌、警笛音效、节奏调整。
- 参考路径：
  - [docs/docs/zh_CN/tutorials/basics/buzz.rst:1-90]

```text
flowchart TD
A["导入music"] --> B{"播放方式"}
B --> |内置旋律| C["music.play(常量)"]
B --> |自定义音符| D["music.play(列表)"]
B --> |频率控制| E["music.pitch(freq, duration)"]
C --> F["结束"]
D --> F
E --> F
```

**章节来源**
- [docs/docs/zh_CN/tutorials/basics/buzz.rst:1-90]

### 按键
- 目标：读取A/B按键状态与中断处理。
- 关键点：value()判断电平、irq触发类型（下降沿/上升沿/低电平/高电平）、回调函数。
- 实践：按键开灯/关灯、中断回调控制蜂鸣器与LED。
- 参考路径：
  - [docs/docs/zh_CN/tutorials/basics/buttons.rst:1-58]

```text
sequenceDiagram
participant 用户 as "用户"
participant 按键 as "Button A/B"
participant 主循环 as "主程序"
participant 中断 as "IRQ回调"
用户->>按键 : 按下/释放
按键-->>主循环 : value()状态
按键-->>中断 : 触发事件
中断-->>主循环 : 执行回调(非阻塞)
```

**章节来源**
- [docs/docs/zh_CN/tutorials/basics/buttons.rst:1-58]

### 触摸
- 目标：读取6个触摸焊盘(P/Y/T/H/O/N)的值与阈值配置。
- 关键点：read()原始值、config(threshold)阈值、is_pressed/was_pressed。
- 实践：触摸不同焊盘点亮不同颜色RGB灯。
- 参考路径：
  - [docs/docs/zh_CN/tutorials/basics/touchpad.rst:1-26]

```text
flowchart TD
S["初始化触摸"] --> R["read()读取原始值"]
R --> C{"是否超过阈值?"}
C --> |是| P["视为按下(is_pressed)"]
C --> |否| N["视为未按下"]
P --> U["执行动作(如点亮LED)"]
N --> U
```

**章节来源**
- [docs/docs/zh_CN/tutorials/basics/touchpad.rst:1-26]

### 麦克风
- 目标：采集环境声音强度并显示。
- 关键点：sound.read()返回12位ADC值(0-4095)。
- 实践：实时显示声音数值，结合阈值触发LED或音乐。
- 参考路径：
  - [docs/docs/zh_CN/tutorials/basics/sound.rst:1-36]

```text
flowchart TD
S["循环采集"] --> R["sound.read()"]
R --> D["显示/处理数据"]
D --> T{"是否超过阈值?"}
T --> |是| A["触发动作(亮灯/发声)"]
T --> |否| W["等待下一次采集"]
A --> W
```

**章节来源**
- [docs/docs/zh_CN/tutorials/basics/sound.rst:1-36]

### 光线
- 目标：采集环境光照强度并实现光控灯。
- 关键点：light.read()返回12位ADC值(0-4095)，阈值判断。
- 实践：暗时亮灯、亮时灭灯。
- 参考路径：
  - [docs/docs/zh_CN/tutorials/basics/light.rst:1-37]

```text
flowchart TD
S["循环采集"] --> R["light.read()"]
R --> C{"是否小于阈值?"}
C --> |是| L["rgb.fill((亮度)) / write()"]
C --> |否| X["rgb.fill((0,0,0)) / write()"]
L --> W["延时/下一轮"]
X --> W
```

**章节来源**
- [docs/docs/zh_CN/tutorials/basics/light.rst:1-37]

### 加速度
- 目标：读取三轴加速度并计算倾斜角度，制作水平球。
- 关键点：get_x/y/z()、roll_pitch_angle()、numberMap映射、acos/degrees计算。
- 实践：观察三轴数值变化、绘制水平球、计算角度。
- 参考路径：
  - [docs/docs/zh_CN/tutorials/basics/accelerometer.rst:1-145]

```text
flowchart TD
S["获取三轴加速度"] --> M["映射偏移量(numberMap)"]
M --> P["计算位置(中心+偏移)"]
P --> V{"是否在中心?"}
V --> |是| G["亮绿灯"]
V --> |否| O["灭灯"]
G --> R["刷新显示/下一轮"]
O --> R
```

**章节来源**
- [docs/docs/zh_CN/tutorials/basics/accelerometer.rst:1-145]

### 网络（进阶）
- 目标：了解WiFi连接与HTTP请求基础。
- 关键点：connectWiFi/disconnectWiFi、enable_APWiFi/disable_APWiFi、HTTP GET/POST。
- 实践：连接热点、获取天气/时间、解析JSON。
- 参考路径：
  - [docs/docs/zh_CN/tutorials/basics/network/index.rst:1-14]

```text
sequenceDiagram
participant 应用 as "应用"
participant WiFi as "WiFi模块"
participant 服务器 as "HTTP服务器"
应用->>WiFi : connectWiFi(ssid, passwd)
WiFi-->>应用 : 连接成功/失败
应用->>服务器 : HTTP GET/POST
服务器-->>应用 : 响应数据(JSON/文本)
应用->>应用 : 解析与展示
```

**章节来源**
- [docs/docs/zh_CN/tutorials/basics/network/index.rst:1-14]

### 串口
- 目标：使用UART与其他设备进行双向通信。
- 关键点：UART(id, baudrate, tx, rx)、write/readline/read、any()检测。
- 实践：与蓝牙模块配对、收发字符串/字节、显示至OLED。
- 参考路径：
  - [docs/docs/zh_CN/tutorials/basics/uart.rst:1-111]

```text
sequenceDiagram
participant 主控 as "掌控板"
participant UART as "UART"
participant 外设 as "蓝牙/模块"
主控->>UART : write("hello")
UART-->>外设 : 发送字节
外设-->>UART : 返回数据
UART-->>主控 : readline()/read()
主控->>主控 : 解码/显示/处理
```

**章节来源**
- [docs/docs/zh_CN/tutorials/basics/uart.rst:1-111]

### 引脚
- 目标：掌握数字/模拟I/O与PWM输出。
- 关键点：PinMode.IN/OUT/PWM/ANALOG、read_digital/write_digital、read_analog/write_analog、irq中断。
- 实践：控制LED闪烁、读取传感器、PWM调光。
- 参考路径：
  - [docs/docs/zh_CN/tutorials/basics/io/index.rst:1-9]

```text
flowchart TD
S["初始化Pin"] --> T{"操作类型"}
T --> |数字| D["read_digital/write_digital"]
T --> |模拟| A["read_analog/write_analog(PWM)"]
T --> |中断| I["irq(handler, trigger)"]
D --> U["应用逻辑"]
A --> U
I --> U
```

**章节来源**
- [docs/docs/zh_CN/tutorials/basics/io/index.rst:1-9]

## 依赖分析
- 模块耦合：
  - mpython模块封装了OLED、RGB、音乐、传感器、网络、串口等高层API。
  - machine/framebuf/SSD1106/NeoPixel等为底层支撑。
  - C级驱动（modmusic/modmotion/modnetwork等）提供高性能实现。
- 外部依赖：
  - 网络需要WiFi与HTTP库。
  - 音频需要codec与扬声器/蜂鸣器。
  - 显示需要OLED或TFT屏幕驱动。
- 潜在风险：
  - 引脚复用冲突（P4/P10）。
  - 高频刷新与采样导致功耗与卡顿。
  - 网络超时与异常未处理导致程序卡死。

```text
graph LR
APP["应用脚本"] --> MPY["mpython模块"]
MPY --> MB["machine/framebuf/SSD1106/NeoPixel"]
MB --> DRV["C级驱动"]
DRV --> HW["硬件外设"]
APP --> NET["网络/串口"]
NET --> DRV
```

## 性能考虑
- 显示优化：批量绘制后统一show()，减少刷新次数。
- 采样策略：合理延时与阈值滤波，避免频繁读取。
- 音频控制：避免长时间阻塞播放，使用异步或定时器。
- 网络请求：设置超时与重试，解析前校验数据完整性。
- 功耗管理：关闭不用的外设，降低刷新频率与亮度。

## 故障排查指南
- REPL无响应：检查串口驱动与波特率，尝试Ctrl-D软重启。
- 显示异常：确认初始化顺序与刷新调用，检查帧缓冲大小。
- RGB无效：确认引脚与写操作，检查供电与信号线。
- 音乐无声：确认蜂鸣器/音频初始化与音量设置。
- 按键/触摸误触发：调整阈值与去抖策略。
- 串口乱码：核对波特率、TX/RX接线与编码解码。
- 网络失败：检查WiFi密码、路由器设置与DNS解析。

## 结论
本入门教程以掌控板为基础，覆盖REPL、显示、灯光、音乐、输入、传感器、通信与引脚等核心能力。通过分步实践与可视化流程，帮助读者建立完整的嵌入式开发认知。建议在掌握单项功能后，逐步组合成综合项目，进一步探索ESP32-S3的高级特性（如TFT显示、WiFi、AI模块等），拓展创客应用的边界。